The CICA Windows Explosion!/The CICA Windows Explosion! - Disc 2.iso/demo/medmfc.zip/EDITOR.DOC

Text File | 1994-08-17 | 28KB | 850 lines

                   Magma Editor DLL for Microsoft Windows
                   --------------------------------------

(C) Copyright 1994 Magma Systems  All Rights Reserved

Magma Systems
15 Bodwell Terrace
Millburn, New Jersey  07041
USA

[phone]  (voice)
[phone]  (fax)
[phone]  (BBS, 9600-1200 N-8-1)

Compuserve : 75300,2062
             To get to our conference, GO MAGMA

Bix        : 'magma'
             To get to our conference, 'join magma'

Internet   : [e-mail]
             [e-mail]



(The following is rough documentation for the Magma Editor DLL.
Please send all your comments to Magma Systems)


Introduction
------------

The Magma Editor DLL is an edit control which provides a powerful
alternative to the standard Microsoft Windows edit control. The
Magma Editor (ME for short) is a line oriented text editing kernel
which can be controlled by an application through a series of
messages or through a high-level C-like macro language. You can
think of the ME DLL as being a "BRIEF in a box".

The editor kernel provides the following features and enhancements
over the standard Windows editoc control :

- The size of the text is limited by the amount of memory Windows
  can globally allocate. On the other hand, the standard Windows
  edit control is limited to 64K of text.

- Regular expression search and substitution

- Various block operations. Line marking, column marking, block
  marking, and discontiguous line marking.

- Keyboard macros

- Messages to read and write to files.

- More varieties of cursor movement. Ability to jump to a specific line,
  and to set bookmarks in the text.

- The ability to be in overstrike as well as in insert mode.


Initializing the Editor Class
-----------------------------

To access the Magma Edit Control dynamic link library from within your
Windows application, you must make the following call :

  if (LoadLibrary("MAGMAED.DLL") < 32)
    return FALSE;

The LoadLibrary() function attempts to load the editor DLL, and if it
succeeds, returns a module handle which is greater than or equal to 32.
If a value less than 32 is returned, then the editor DLL could not be loaded.

You must make sure that the DLL is either present in your current
working directory, or in a directory which is in your DOS path.

The startup routine inside of MAGMAED.DLL registers a global class
called "MagmaEdit". This is the class name of an editor control.



Creating an Editor Window
-------------------------
Creating an editor window is just like creating any other control window.
You can use a call to the CreateWindow function or, if you use the
editor window as part of a dialog box, you can specify the control
in your RC file.

A typical use of the CreateWindow function is as follows:

HWND hEdit;
hEdit = CreateWindow("MagmaEdit",
                     NULL,
                     WS_CHILD | WS_VISIBLE | WS_MAXIMIZE,
                     0, 0, 0, 0,
                     hWnd,
                     idCtrl,
                     GetWindowWord(hWnd, GWW_HINSTANCE),
                     (LPSTR) lpFileName);

The classname is "MagmaEdit", and it has no initial text. The window
style dictates that it is a visible child window, with 'hWnd' as the parent
window. You may give the editor window a unique control identifier in
order to distinguish it from other controls or editor windows. The size
is 0, 0, 0, 0. Finally, the final argument may be the name of the
file which will be associated with this editor window. If the file already
exists, then the contents of the file will be read into the editor window.


Limitations
-----------

The Magma Edit control has no size limitations. It can use as much memory
as Windows will globally allocate. The standard Windows edit control can only
use at most 64K of data because it uses LocalAlloc for the edit buffer.




                      Message Reference
                      -----------------

Below is a list of messages which you can send to an editor window
in order to perform editing operations, cursor movement, or
configuration of the editor. The general form of sending a
message is

  result = SendMessage(hWndEdit, ME_xxx, wParam, lParam);

Most of the editor commands return TRUE if the command was performed
successfully, and FALSE if the command failed.


Cursor Movement commands
------------------------
ME_MOVEUP             Move to the previous line
ME_MOVEDOWN           Move to the next line
ME_MOVELEFT           Move left one character
ME_MOVERIGHT          Move right one character
ME_MOVEBOL            Move to the beginning of the current line
ME_MOVEEOL            Move to the end of the current line
ME_MOVENEXTWORD       Move to the next word
ME_MOVEPREVWORD       Move to the previous word
ME_MOVENEXTPARA       Move to the next paragraph
ME_MOVEPREVPARA       Move to the previous paragraph
ME_MOVETOPOFWINDOW    Move to the upper-left corner of the editing window
ME_MOVEBOTOFWINDOW    Move to the lower-right corner of the editing window
ME_MOVENEXTPAGE       Move to the next page of text
ME_MOVEPREVPAGE       Move to the previous page of text
ME_MOVETOPOFBUFFER    Move to the top of the editing buffer
ME_MOVEBOTOFBUFFER    Move to the last character in the editing buffer
For all of the above commands, wParam and lParam are not used. The
value TRUE is returned if the command was successful, and FALSE is
returned if the command failed.

ME_GOTOLINE
  wParam
    GOTOLINE_ABS  - lParam is the absolute line number
    GOTOLINE_NEXT - lParam is the # of lines from the current line
    GOTOLINE_PREV - lParam is the # of lines back from the current line
    GOTOLINE_LAST - go to the last line of the file. lParam is ignored.
  lParam is the line number

ME_MATCHBRACE
If the character at the current position is one of the following :
  {, }, (, ), [, ], "
attempts to find the matching brace or quote. If the match is found,
the current position will be moved to the matched character.
  Returns TRUE if successful, FALSE if not.


Bookmarks
---------
ME_MOVETOBOOKMARK
  Moves the cursor to a specific bookmarked location.
Parameters
  wParam is the letter of the bookmark
  lParam is not used

ME_SETBOOKMARK
  Sets a bookmark at the current cursor position.
Parameters
  wParam is the letter of the bookmark to set
  lParam is not used

ME_REMOVEBOOKMARK
  Removes one or more bookmarks from the editing buffer.
Parameters
  wParam is the letter of the bookmark. It can be 'a' through 'z'. If
    wParam is the special value BOOKMARK_REMOVEALL, then all of the
    bookmarks associated with the editing buffer will be removed.
  lParam is not used
Returns
  TRUE



Character Insertion & Deletion
------------------------------
ME_BACKSPACE
  Backspaces over the previous character and erases it
Parameters
  wParam is not used
  lParam is not used

ME_DELCHAR
  Delete the character at the current position. If the character is a newline,
  the the next line will be joined to the current line.
Parameters
  wParam is not used
  lParam is not used

ME_DELEOL
  Deletes all characters from the current line starting at the
  current position and going until the end of the line
Parameters
  wParam is not used
  lParam is not used

ME_DELWORD
  Deletes the current word.
Parameters
  wParam is not used
  lParam is not used

ME_INSERTCHAR
  Inserts a character at the current position. This function
  obeys the state of the editor's insert/overstrike mode.
Parameters
  wParam is the ASCII character to insert at the current position
  lParam is not used


ME_INSERTSTRING
  Inserts a string into the editor at the current position.
Parameters
  wParam is ME_OVERSTRIKE_MODE if you want to overstrike the existing
    text at the current position in the buffer. Any other value of
    wParam will insert the text at the current position in the buffer.
  lParam is a far pointer to the text to insert. The text may have
    embedded tab characters (\t) or newlines (\n).
Returns
  TRUE if the text was inserted, FALSE if not.
Example
  SendMessage(hWndEdit, ME_INSERTSTRING, ME_INSERT_MODE,
              (LONG) (LPSTR) "This is line 1\nAnd this is line 2\n");


ME_TOGGLEINSERT
  Toggles or sets the state of the insert/overstrike mode
Parameters
  wParam can be
    INSERTMODE_TOGGLE - toggle the state
    INSERTMODE_ON     - sets insert mode
    INSERTMODE_OFF    - sets overstrike mode
  lParam is not used

ME_TOGGLEWORDWRAP
  Toggles the current state of the wordwrap flag.
Parameters
  wParam can be
    WORDWRAP_OFF      - turns wordwrap off
    WORDWRAP_ON       - turns wordwrap on
    WORDWRAP_TOGGLE   - toggles wordwrap mode
  lParam is not used.
Returns
  Nothing.


File I/O
--------
ME_OPENFILE
  Inserts the contents of a file at the current cursor position.
Parameters
  wParam is 0 if lParam points to a valid filename. You can pass
    the handle of an open file in wParam. If you do this, then lParam
    must be 0.
  lParam is a far pointer to the name of the file to read. If lParam
    is 0, then wParam is assumed to contain the handle of an open file.
Returns
  TRUE if successful, FALSE if not.

ME_WRITEFILE
  Writes the contents of the editor buffer to a file.
Parameters
  wParam is usually 0. If lParam is NULL, wParam may contain a
    file handle.
  lParam is a far pointer to the name of the file to write to.
  If the lParam is NULL and wParam is 0, then the filename already associated
  with  the editor window is used. If lParam is NULL and wParam is not zero,
  then wParam is interpeted as a file handle to write to.
Returns
  TRUE if successful, an error code if not. The error code can be
  one of the following values :
    EN_ERRCREATING  could not create the file
    EN_ERRWRITING   could not write out the entire editor buffer to
                    the file.



Search & Substitute commands
----------------------------
ME_FSEARCH
  Search forward (from the current position) for a pattern.

ME_BSEARCH
  Search backwards (from the current position) for a pattern.

ME_FREPLACE
  Search forward (from the current position) for a pattern and substitute
  with a pattern.

ME_BREPLACE
  Search backward (from the current position) for a pattern and substitute
  with a pattern.

Parameters
  wParam is not used
  lParam :

  For the search and substitute commands, the format of the data passed
  into lParam is :

  UINT fFlags;
    SEARCH_CASE_INSENSITIVE    - the search is case insensitive
    SEARCH_NO_REGEXP           - the pattern is not considered to be
                                 a regular expression
    SEARCH_PROMPT_ON_REPLACE   - prompts the user for each replacement
    SEARCH_SELECTMATCH         - the matched text is highlighted and selected

  char szPattern[];    the ASCII search pattern, NULL terminated
  char szReplace[];    the ASCII replacement pattern, NULL terminated

  The SEARCH_PROMPT_ON_REPLACE flag and szReplace[] string are only valid
  in the Substitute command

  If lParam is NULL, then the editor will automatically bring up dialog
  boxes for the search and substitute commands. This will allow you to
  interactively enter the search and replace strings and the various
  options.

Returns
  TRUE if the pattern was found, FALSE if not.


ME_SEARCHAGAIN
  Repeats the previous search operation.
Parameters
  wParam and lParam are not used

ME_REPLACEAGAIN
  Repeats the previous replace operation.
Parameters
  wParam and lParam are not used

Returns
  TRUE if the pattern was found, FALSE if not.


ME_QUERYSEARCHSTRING
  Retrieves the last string used for searching.
Parameters
  wParam is not used
  lParam is the far pointer to a buffer which the search string will be copied
    to. lParam can be NULL.
Returns
  The length of the search string, or 0 or there was no previous search
  string.



Help
----
ME_HELPONWORD
  Gets help on the word under the cursor. The Windows help file used is
  the one which is in the APIHELP entry in [options] section of the
  MAGMAED.INI file.
Parameters
  wParam and lParam are not used
Returns
  TRUE if successful, FALSE if not.


Selecting, cutting, copying and pasting text
--------------------------------------------
ME_APPENDLINE
  Appends a blank line after the current line
Parameters
  wParam and lParam are not used

ME_CASELOWER
  Changes the case of the selected text to all lower case
Parameters
  wParam and lParam are not used

ME_CASEUPPER
  Changes the case of the selected text to all upper case
Parameters
  wParam and lParam are not used

ME_COPY
  Copies the current selection, any marked lines, or the current line.
  The copied text is placed into the clipboard.
  If there is a currently marked selection, then this text is copied.
  If there is no selected text, then the current line is copied.
  The clipboard is cleared before the copied text is placed into it.
Parameters
  wParam and lParam are not used

ME_CUT
  Deletes the current selection, any marked lines, or the current line.
  The deleted text is placed into the clipboard.
  If there is a currently marked selection, then this text is deleted.
  If there is no selected text, then the current line is deleted.
  The clipboard is cleared before the deleted text is placed into it.
Parameters
  wParam and lParam are not used

ME_CUTAPPEND
  Deletes the current selection, any marked lines, or the current line.
  The deleted text is placed into the clipboard.
  If there is a currently marked selection, then this text is deleted.
  If there is no selected text, then the current line is deleted.
  The selected text is appended to the clipboard.
Parameters
  wParam and lParam are not used

ME_DELLINE
  Deletes the current line or any marked lines. The deleted lines are
  not placed into the clipboard.
Parameters
  wParam and lParam are not used

ME_DUPLINE
  Duplicates the current line and inserts it after the current line.
Parameters
  wParam and lParam are not used

ME_INSERTLINE
  Inserts a blank line before the current line
Parameters
  wParam and lParam are not used

ME_MARKLINE
  Toggles the marked state of the current line.
Parameters
  wParam and lParam are not used

ME_MARKLINERANGE
  Marks all lines from the current line up to the previously marked line.
  The previously marked line must physically above the curent line.
Parameters
  wParam and lParam are not used

ME_PASTE
  Inserts the contents of the pick buffer at the current position
Parameters
  wParam and lParam are not used

ME_RECTMARK
  Starts or ends a 'column' selection. If this message is sent when there
  are no selected areas of text, then the editor will 'mark' the
  current cursor position. You can then move the cursor anywhere in the
  buffer. When the second ME_STREAMMARK message is received by the
  editor, it will select the columns of text between the starting and ending
  selection points.
Parameters
  wParam and lParam are not used

ME_RESETMARK
  Clears all selections from the current buffer. If any text is selected,
  then it will become deselected.
Parameters
  wParam and lParam are not used

ME_STREAMMARK
  Starts or ends a 'stream' selection. If this message is sent when there
  are no selected areas of text, then the editor will 'mark' the
  current cursor position. You can then move the cursor anywhere in the
  buffer. When the second ME_STREAMMARK message is received by the
  editor, it will select all text between the starting and ending
  selection points.
Parameters
  wParam and lParam are not used

ME_TAB
ME_BACKTAB
  Indents the selected lines rightwards or leftwards. The ME_TAB command
  pushes the text rightwards, and the ME_BACKTAB command pushes the text
  leftwards.
Parameters
  wParam and lParam are not used


Undo
----
ME_REDO
  Undoes the previous undo.
Parameters
  wParam and lParam are not used

ME_UNDO
  Undoes the previous editing command.
Parameters
  wParam and lParam are not used


Configuring the editor
----------------------
ME_OPTIONDLG
  Invokes the "Options" dialog box. This provides an interactive
  way for the user to configure the editor.
Parameters
  wParam and lParam are not used

ME_SETOPTION
  Sets a specific editor option.
Parameters
  wParam is the new value
  lParam is a far pointer to the name of the option


Name          Default   Meaning
-----------   -------   -------
AutoIndent    1         Are new lines auto-indented
EntabLine     0         Lines are entabbed when written to a file
GoFreeSpace   1         Can the cursor move into space beyond the end-of-line
HighBitsOff   0         Editor masks out the high bit of characters
IndentAmount  2         The amount of space each indent/undent command shifts
InsertMode    1         The initial insert/overstrike mode  (1 = insert)
RightMargin   80        The margin where wordwrapping will take effect
TabFill       32        The fill character used for tabs
TabIncrement  8         The width of a tab stop
UndoEnabled   1         Undo enabled
UseRealTabs   0         Use real tabs or insert spaces instead of tabs
Wordwrap      0         Wordwrap enabled

ME_QUERYOPTION
  Queries the current value of a specific editor option.
Parameters
  wParam is not used.
  lParam is a far pointer to the name of the option
Returns
  The current value of the editor option.


ME_SETTEXTCOLOR
  Sets the color of the text.
Parameters
  wParam not used
  lParam is the RGB color

ME_SETBKCOLOR
  Sets the color of the editor window background.
Parameters
  wParam not used
  lParam is the RGB color

EM_SETBKGNDCOLOR  (Chicago compatible)
  Sets the color of the editor window background.
Parameters
  wParam is TRUE to use system color, FALSE for RGB value in lParam
  lParam is the RGB value
Returns
  The old background color



Miscellaneous commands
----------------------
ME_GETCURRWORD
  Retrieves the word under the cursor and puts it in an app-passed buffer.
Parameters
  wParam is the length of the buffer
  lParam is a far pointer to the buffer to copy the word into
Returns
  The length of the string if successful, 0 if not.


ME_QUERYSTATUS
  This message retrieved certain information about the editing buffer.
  Information includes the current column, current line number, and the
  total number of lines in the buffer.
Parameters
  wParam is not used.
  lParam is a far pointer to an MAGMAED_STATUS structure.
Returns
  TRUE if the infomation was retrieved, FALSE if not.

Keyboard Macros
---------------
ME_KEYMACDEFINE
  Starts and stops the recording of a keyboard macro. To begin recording
  a keyboard macro, send the ME_KEYMACDEFINE message to the editor. To
  stop the recording, send this message again.
Parameters
  wParam and lParam are not used

ME_KEYMACPLAY
  Plays the currently-defined keyboard macro
Parameters
  wParam and lParam are not used


Notification messages
---------------------
MEN_UPDATE
  This notification code is sent when the state of the editor has changed.
  A WM_COMMAND message will be sent to the window which is the parent of
  the editor window. The wParam will be the control ID of the editor
  window, the LOWORD of the lParam will be the window handle of the
  editor window, and the HIWORD of the lParam will be the MEN_UPDATE
  code.

  A typical use for this message is to update the "editor decorations"
  in your application when something in the editor has changed. For
  example, if your application maintains a status line for the
  editor, then you can use the following code in your application
  in order to update the status line:

    case WM_COMMAND:
      if (HIWORD(lParam) == MEN_UPDATE)
      {
        InvalidateRect(hWndStatus, (LPRECT) NULL, FALSE);
        break;
      }


Windows/API Messages Supported
------------------------------
The following messages are provided for compatibility with the
standard Windows edit control.


WM_GETTEXT
  Retrieves the contents of the edit control and puts the text into the
  passed memory location.
Parameters
  wParam is the maximum size of the text to be copied.
  Note:
    A limitation is that wParam contains the max length of the buffer,
    which under 16-bit Windows, can be at most 64K. So, we will add
    a little extension here. If wParam is 0, then we will not check
    the length of the buffer.
  lParam is a far pointer to the memory location which will receive the
    text.
Returns
  The number of bytes copied into the memory location, or 0 if not
  successful.

WM_GETTEXTLENGTH
  Queries the length of the text in the edit control.
Parameters
  wParam and lParam are not used.
Returns
  The number of characters in the edit control. This double-word value
  can be greater than 64K.

WM_SETTEXT
  Sets the contents of the edit control to the specified text.
Parameters
  wParam is not used.
  lParam is a far pointer to the text to set.
Returns
  TRUE if successful, FALSE if not.


EM_GETFIRSTVISIBLELINE
  Queries the line number of the line which is at the top of the
  editor window.
Parameters
  wParam is not used.
  lParam is not used.
Returns
  The 0-based line number of the line at the top of the window.

EM_GETLINE
  Retrieves the contents of a specified line.
Parameters
  wParam is the 0-based line number of the line to query.
  lParam is a far pointer to a memory location where the contents
    of the line will be copied to.
Returns
  The number of bytes copied.

EM_GETLINECOUNT
  Queries the number of lines in the edit control.
Parameters
  wParam is not used.
  lParam is not used.
Returns
  The number of lines in the editor.

EM_GETSELTEXT  (Chicago compatible)
  This message retrieves the text which is currently selected.
Parameters
  wParam is 0
  lParam is a far pointer to a buffer which the text will be placed into.
Returns
  TRUE if there was selected text, FALSE if not.
Notes
  The editor does not check the length of the the buffer pointed to by
  lParam. It is up to the application to ensure that the buffer is large
  enough to hold the selected text.


EM_LINEFROMCHAR
  Given a 0-based index into the editor, returns the line number of
  the line which contains the character.
Parameters
  wParam contains the 0-based index of the character.
  Note :
    A limitation is that wParam contains the max length of the buffer,
    which under 16-bit Windows, can be at most 64K. So, we will add
    a little extension here. If lParam is not 0, then we will use the
    value in lParam as the index.
  lParam must be 0 if you are using wParam as the index. Otherwise,
    lParam will be used as the index.
Returns
  The 0-based line number.

EM_EXLINEFROMCHAR  (Chicago compatible)
  See the EM_LINEFROMCHAR message.
Parameters
  wParam is 0
  lParam is the index

EM_LINEINDEX
  Given the number of a line, returns the 0-based index of the first
  character on that line.
Parameters
  wParam is the 0-based line number. If lParam is not 0, then lParam is
    used as the line number.
  lParam should be 0 if you are using wParam to hold the line number.
    Otherwise, lParam can hold the line number.
Returns
  The 0-based index of the first character on the line. If wParam contains
  a line number which is greater than the number of lines in the edit
  control, then -1 is returned.

EM_LINELENGTH
  Queries the number of characters in a certain line.
Parameters
  wParam is the 0-based line number. If lParam is not 0, then lParam
    holds the line number.
  lParam should be 0 if wParam holds the line number. Otherwise, the
    value in lParam will be used as the line number.
Returns
  The number of characters in the line, or 0 if the line number
  does not exist.

EM_GETMODIFY
  Queries the modification state of the edit control.
Parameters
  wParam is not used.
  lParam is not used.
Returns
  Non-zero if the edit control has been modified, 0 if not.

EM_SETMODIFY
  Sets the modification state of the edit control.
Parameters
  wParam is the new modification state. It should be non-zero if the
    edit control should be considered to have been modified, and zero
    if you want to clear the modification state.
  lParam is not used.
Returns
  The new modification state.

EM_GETSEL
  Queries the current selection points.
Parameters
  wParam and lParam are not used.
Returns
  If an area of text has been selected, then the low word of the return
  value is the starting index of the selection and the high word of
  the return value is the index of the last selected character plus 1.
  If an area is not selected, then both the low word and high word of the
  return value contain the index where the cursor is currently positioned.

EM_REPLACESEL
  Replaces the selected text with another string.
Parameters
  wParam is not used.
  lParam is a far pointer to a string to use to replace the selected text
  with.

EM_SETSEL
  Sets the current selection points. Each selection point must be an index
  less than 64K. See the EM_EXSETSEL message if you need to select an
  area in a buffer which contains more than 64K of text.
Parameters
  wParam is 0.
  The low word of lParam is the index of the starting point of the
  selected area. The high word of lParam is the index of the first
  character after the starting selection index which is not selected.


EM_EXGETSEL  (Chicago compatible)
  Queries the current selection points. Each selection point can be
  a number greater than 64K.
Parameters
  wParam is 0
  lParam is a far pointer to a CHARRANGE structure

EM_EXSETSEL  (Chicago compatible)
  Sets the current selection points. Each selection point can be
  a number greater than 64K.
Parameters
  wParam is 0
  lParam is a far pointer to a CHARRANGE structure


EM_SETREADONLY
  Modifies the 'read-only' state of the edit control.
Parameters
  wParam is non-zero if the read-only state should be set, and zero
    if it should be cleared.
  lParam is not used.
Returns
   TRUE if successful, FALSE if not.

EM_SETTABSTOPS
  Sets the tab stops of the edit control.
Parameters
  wParam specifies the number of tab stops contained in the lpTabs array
    pointed to by lParam. If wParam is 1, then the lpTabs[0] contains
    tab increment multiplied by 4; the tabs will be set every
    'lpTabs[0]/4' number of columns. If wParam is 0, then the default tab
    settings are used. If wParam is greater than 1, then lpTabs is an array
    of tab stops.

  lParam is a far pointer to an array of tab stops. Each tab stop
    represents a column number multiplied by 4. The value 4 is equivalent
    to the Windows dialog unit.
Returns
  TRUE if the tabs were set, FALSE if not.

Notification Messages
---------------------
EN_CHANGE     the contents of the edit control have been altered
EN_HSCROLL    the edit control's horizontal scrollbar has been clicked on
EN_KILLFOCUS  the edit control is losing the focus
EN_SETFOCUS   the edit control has gained the focus
EN_VSCROLL    the edit control's horizontal scrollbar has been clicked on
MEM_UPDATE    the editing status has changed. This message is usually
              used to determine when the status line should be refreshed.